3D Graphics Programming with QuickDraw 3D 1.5.4

Group Positions

You access an object within a group (for example, to remove the object from the group or to replace it with some other object) by referring to the object's group position. A group position is a pointer to a private (that is, opaque) data structure maintained internally by QuickDraw 3D. A group position is defined by the TQ3GroupPosition data type.



 
typedef struct TQ3GroupPositionPrivate      *TQ3GroupPosition;

You receive a group position for an object when you first insert the object into the group (for example, by calling Q3Group_AddObject ). In general, however, you don't need to maintain that information, because you can use QuickDraw 3D routines to walk through a group. For instance, you can get the group position of the first object in a group by calling Q3Group_GetFirstPosition . Then you can retrieve the positions of all subsequent objects in the group by calling Q3Group_GetNextPosition .

An object's group position is valid only as long as that object is in the group. When you remove an object from a group, the corresponding group position becomes invalid. Similarly, when you remove all objects from a group (for example, by calling Q3Group_EmptyObjects ), the group positions of those objects become invalid.

See "Accessing Objects by Position" for sample code that illustrates how to traverse a group using group positions.